Since Forth uses a virtual memory arrangement and the screen concept to manage the disk, I felt that providing words to access CBM disk files would be a waste of memory space. Blazin' Forth contains all the primitives necessary to write words to access CBM disk files, or other serial devices. This appendix describes how to do this from Forth, for users whose applications require such access.
(OPEN) ( file# device# sa address-of-filename filename-length -- error code)
This word requires 5 parameters, as described above. This is the same as from BASIC, with the exception of the address of filename, and the length of the filename. The address can be any memory location which stores a legal filename. Using Blazin' Forths string handling words, an open statement would look like this:
8 8 8 " LETTERS,S,R" COUNT (OPEN)
Which opens a sequential file called "LETTERS" for a read, with logical file# 8, on device 8, with a secondary address of 8. Note that (OPEN) returns an error code, which is 0 (false) if everything was ok, and otherwise is one of the error codes as described in the Programmers Reference Guide. This error code may be processed by your program, ignored, or you may use the Blazin' Forth word IOERR. (see IOERR for more info on this.)
If you intend to use (OPEN) a lot, you will probably want to define a different version:
: OPEN COUNT (OPEN) IOERR ;
With this new word, the OPEN statement becomes:
8 8 8 " LETTERS,S,R" OPEN
If you need to open a file to a device which doesn't require a filename, such as a printer or plotter, just use a zero as the filename and length:
4 4 0 0 0 (OPEN) IOERR
The above will open a channel to a printer connected as device #4.
CLOSE ( File# -- )
This will close an already open file. Example:
8 CLOSE ( closes file# 8 )
To send or receive data from the device, you will need the following words:
(CMDOUT) ( File# -- errorcode)
This is an I/O redirection word. Executing this word will cause all system output to be directed to the logical file whose number is on the stack. All system output words: EMIT , SPACES , TYPE , ." .( etc. will direct data to this device. Note that you must have opened a channel to the file before using this word. The error code is suitable for being read by IOERR . Example:
8 (CMDOUT) IOERR ( send all output to file# 8 )
(CMDIN) ( File# -- errorcode)
Another I/O redirection word. Executing this word will cause all system input to be obtained from the file whose number is on the stack. All system input words, EXPECT KEY ?KEY etc. will recieve data from this file. Note that you must have previously opened a channel to the file before using this word. The error code is suitable for being read by IOERR. Example:
8 (CMDIN) IOERR ( get all input from file# 8)
CMDOUT ( -- )
Executing this word will restore the default input and output channels. All input will now come from the keyboard, and all output will be sent to the screen. Note that all files remain open.
IOERR ( errorcode -- )
This word will execute an error abort if the value on the top of the stack is non-zero. It will decode the error# and type the appropriate message. Note that if you do not want your application to halt on an error, you should not use this word.
Using the above words, it is a simple matter to send or receive data from a disk. For example:
: GET# ( FILE# -- character )
(CMDIN) IOERR ?KEY CMDOFF ;
This defines a word which works exactly like GET# in BASIC. Note the use of CMDOFF at the end of the word to restore default devices. This is generally the best practice to follow, since the serial bus does not handle multiple channels being connected all that well.
The following word is an example of how to implement PRINT# in Forth:
: PRINT# ( address file# -- )
(CMDOUT) IOERR COUNT TYPE ( send text at address to disk)
CMDOFF ( restore default devices) ;
If you require more exotic file handling words, they are also easy to define. Just follow the examples given above. The following are also useful in handling disk serial bus access:
(?DISC) ( --- flag )
This word reads the disk error channel, leaving a true flag if a disk error has occurred. This is useful if you want your program to handle errors, since the higher level ?DISC will abort on an error. Note that the command channel must be opened before using this word. Example:
: RECEIVE 8 GET# (?DISC) IF .DERR ABORT THEN ;
This word will print the disk error message, and halt execution if there is an error.
*fp0
.DERR ( -- )
Prints the disk error message stored in the error message buffer. Note that this is only valid after (?DISC) or (R/W).
STATUS ( -- status )
Pushes the serial bus status byte on the stack. Same as ST in BASIC.
*cn1;2: System DEFERed words.*cn0
The system contains several DEFERed words for your convenience. These allow changes to be made in the actual Forth system itself:
PRINTER NOPRINTER
These words are described in the section on I/O.
PUNCT? ( char -- flag)
This word controls the characters accepted by NUMBER. In order to conform to the 83 standard, Blazin' Forth will only accept a period when entering double numbers. All other characters will result in an error. In order to change this behaviour, code a new word, which accepts the characters you wish, and then execute:
' NEW.PUNCT IS PUNCT?
Of course, NEW.PUNCT must accept the same inputs, and provide the same outputs, as the older version.
R/W ( addr blk# flag -- )
This word is the virtual memory interface primitive. It may be altered to add new disk handling operations to FORTH, such as a file system.
*cn1;3: Vocabulary Structure*cn0
Blazin' Forth uses the same tree structured vocabulary linkages as FIG forth. Some of the newer dynamic vocabulary structures were examined, but found unsatisfactory. Most people seem to prefer FIG to forth-79, but all reports are not in as far as the newer efforts are concerned. Comments on these newer vocabulary structures are welcomed.
In Blazin' Forth, a new vocabulary is chained to the vocabulary within which it is created. For example:
FORTH DEFINITIONS ( Put all definitions in FORTH vocabulary)
VOCABULARY CARTON ( chain CARTON to FORTH )
CARTON DEFINITIONS ( Put all definitions in CARTON vocabulary)
VOCABULARY EGGS ( Chain EGGS to CARTON, which chains to FORTH )
FORTH DEFINITIONS ( restore Forth )
*fp0
*cn1;4: Misc. Information*cn0
You may change the screen color defaults of Blazin' Forth to ones more suitable to your monitor or tv. Example:
0 0 +ORIGIN C! ( border color)
4 1 +ORIGIN C! ( Screen color)
6 2 +ORIGIN C! ( character color)
Once this is done, RESTART, or RUN/STOP RESTORE will default to the new colors, as will NODRAW etc. Once you find an acceptable combination, you can save the system using SAVE-FORTH. Note that some early model 64's have a screen editing bug which appears when trying to delete across a screen boundary. The words LOAD RUN will appear, and although the cursor will continue to flash, the computer will not respond to any input. The only solution, (aside from obtaining a ROM upgrade from CBM) is to select a color with a low number, such as 0 or 1. Note that if this problem occurs, it is NOT a Blazin' Forth bug.
You may desire to convert the present editor to a fullscreen editor. This is easily accomplished. Probably the easiest way is to define 16 words, for example, 0: 1: 2: etc., or P1 P2 or whatever you like. These words should accept 64 characters from the input stream, and then move them to the appropriate postion in the buffer for that screen. (In other words, they combine the functions of T , in selecting the line, and P in placing the line in the buffer.) You can then modify LIST so that instead of line numbers, it lists out with your words 0: 1: 2: or whatever you used. Once this has been done, you may use the resident features of the 64's screen editor to their full extent. I didn't provide such an editor with the system since it was desired to make this system as compatible with the book Starting Forth as possible.
You may define additional USER variables. User offsets from 58 to 198 are available to you for new user variables. Offsets less than 58 are used by the system. Blazin' Forth will initialize the entire user area to zero's on a RESTART or on POWERUP. Note that this is not a Standard Feature.
The system is configured for use with one 4040 compatible dual drive. Single drives are usable with Blazin' Forth, but the highest screen accessable is 166. Note that it is be possible to interface additional drives, or non-standard drives to Blazin' Forth by vectoring R/W. (see: DEFERed words.) Note that users of single disk drives will not receive an ILLEGAL SCREEN error if they attempt to access screens greater than 166. (R/W) may bepatched, or modified to do this if so desired. (See: Defered words)
Membership in the Forth Interest Group (FIG) is encouraged. They provide a magazine, FORTH DIMENSIONS, which presents a variaty of interesting articles and applications. They also supply books, reprints, and sponsor Forth seminars. Of particular interest to those using Blazin' Forth is that they supply copies of the FORTH-83 standard ( $15.00 at this writing). Membership at this writing is $15.00 per year, which includes a free subscription to Forth Dimensions, and may obtained by writing to:
The Forth Interest Group
P.O. Box 8231
San Jose
CA 95155
USA
The Forth Standards Team is responsible for the development of new Forth standards. The welcome comments and proposals. The may reached at:
